joachim99@11: <?xml version="1.0" ?>
joachim99@11: <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
joachim99@11:   <!ENTITY kdiff3 "<application>KDiff3</application>">
joachim99@11:   <!ENTITY kappname "&kdiff3;">
joachim99@11:   <!ENTITY package "kdeextragear-1">
joachim99@11:   <!ENTITY % addindex "IGNORE">
joachim99@11:   <!ENTITY % English "INCLUDE">
joachim99@11: ]>
joachim99@11: 
joachim99@11: <book lang="&language;">
joachim99@11: 
joachim99@11: <!-- This header contains all of the meta-information for the document such
joachim99@11: as Authors, publish date, the abstract, and Keywords -->
joachim99@11: 
joachim99@11: <bookinfo>
joachim99@11: <title>The &kdiff3; Handbook</title>
joachim99@11: 
joachim99@11: <authorgroup>
joachim99@11: <author>
joachim99@11: <!--<personname>-->
joachim99@11: <firstname>Joachim</firstname>
joachim99@11: <surname>Eibl</surname>
joachim99@11: <!--</personname>-->
joachim99@11: <affiliation><address>
joachim99@11:    <email>joachim.eibl@gmx.de</email>
joachim99@11: </address></affiliation>
joachim99@11: </author>
joachim99@11: </authorgroup>
joachim99@11: 
joachim99@11: <!-- TRANS:ROLES_OF_TRANSLATORS -->
joachim99@11: 
joachim99@11: <copyright>
joachim99@11: <year>2002-2003</year>
joachim99@11: <holder>Joachim Eibl</holder>
joachim99@11: </copyright>
joachim99@11: <!-- Translators: put here the copyright notice of the translation -->
joachim99@11: <!-- Put here the FDL notice.  Read the explanation in fdl-notice.docbook
joachim99@11:      and in the FDL itself on how to use it. -->
joachim99@11: <legalnotice>&FDLNotice;</legalnotice>
joachim99@11: 
joachim99@11: <!-- Date and version information of the documentation
joachim99@11: Don't forget to include this last date and this last revision number, we
joachim99@11: need them for translation coordination !
joachim99@11: Please respect the format of the date (YYYY-MM-DD) and of the version
joachim99@11: (V.MM.LL), it could be used by automation scripts.
joachim99@11: Do NOT change these in the translation. -->
joachim99@11: 
joachim99@11: <date>2003-09-15</date>
joachim99@11: <releaseinfo>0.9.70</releaseinfo>
joachim99@11: 
joachim99@11: 
joachim99@11: <abstract>
joachim99@11: <para></para>
joachim99@11: <para>
joachim99@11:    &kdiff3; is a file and directory diff and merge tool which
joachim99@11: <itemizedlist>
joachim99@11: <listitem><para>compares and merges two or three text input files or directories,</para></listitem>
joachim99@11: <listitem><para>shows the differences line by line and character by character(!),</para></listitem>
joachim99@11: <listitem><para>provides an automatic merge-facility,</para></listitem>
joachim99@11: <listitem><para>has an editor for comfortable solving of merge-conflicts,</para></listitem>
joachim99@11: <listitem><para>provides networktransparency via KIO,</para></listitem>
joachim99@11: <listitem><para>and is very colorful (by default) :-)</para></listitem>
joachim99@11: </itemizedlist>
joachim99@11: </para><para>
joachim99@11:    This document describes KDiff3-version 0.9.70.
joachim99@11: </para>
joachim99@11: </abstract>
joachim99@11: 
joachim99@11: <!-- This is a set of Keywords for indexing by search engines.
joachim99@11: Please at least include KDE, the KDE package it is in, the name
joachim99@11:  of your application, and a few relevant keywords. -->
joachim99@11: 
joachim99@11: <keywordset>
joachim99@11: <keyword>KDE</keyword>
joachim99@11: <keyword>kdeextragear</keyword>
joachim99@11: <keyword>kdiff3</keyword>
joachim99@11: <keyword>diff</keyword>
joachim99@11: <keyword>merge</keyword>
joachim99@11: <keyword>CVS</keyword>
joachim99@11: <keyword>triplediff</keyword>
joachim99@11: <keyword>compare</keyword>
joachim99@11: <keyword>files</keyword>
joachim99@11: <keyword>directories</keyword>
joachim99@11: <keyword>version control</keyword>
joachim99@11: <keyword>three-way-merge</keyword>
joachim99@11: <keyword>in-line-differences</keyword>
joachim99@11: <keyword>synchronise</keyword>
joachim99@11: <keyword>kpart</keyword>
joachim99@11: <keyword>kio</keyword>
joachim99@11: <keyword>networktransparent</keyword>
joachim99@11: <keyword>editor</keyword>
joachim99@11: </keywordset>
joachim99@11: 
joachim99@11: </bookinfo>
joachim99@11: 
joachim99@11: <chapter id="introduction"><title>Introduction</title>
joachim99@11: <sect1 id="why"><title>Yet Another Diff Frontend?</title>
joachim99@11: <para>
joachim99@11: Several graphical diff tools exist. Why choose KDiff3? Let me say, why I wrote it.
joachim99@11: </para><para>
joachim99@11: KDiff3 started because I had to do a difficult merge. Merging is necessary when several
joachim99@11: people work on the same files in a project. A merge can be somewhat automated, when the
joachim99@11: merge-tool not only has the new modified files (called "branches"), but also the original file
joachim99@11: (called "base"). The merge tool will automatically choose any modification that was only
joachim99@11: done in one branch. When several contributors change the same lines, then the merge tool
joachim99@11: detects a conflict which must be solved manually.
joachim99@11: </para><para>
joachim99@11: The merge then was difficult because one contributor had changed many things and corrected
joachim99@11: the indentation in many places. Another contributor also had changed much text in the same file,
joachim99@11: which resulted in several merge conflicts.
joachim99@11: </para><para>
joachim99@11: The tool I used then, only showed the changed lines, but not what had changed within these
joachim99@11: lines. And there was no information about where only the indentation was changed. The merge
joachim99@11: was a little nightmare.
joachim99@11: </para><para>
joachim99@11: So this was the start. The first version could show differences within a line and showed white space differences.
joachim99@11: Later many other features were added to increase the usefulness.
joachim99@11: </para><para>
joachim99@11: For example if you want to compare some text quickly, then you can copy it to the clipboard and
joachim99@11: paste it into either diff window.
joachim99@11: </para><para>
joachim99@11: A feature that required a big effort was the directory comparison and merge facility, which turned
joachim99@11: the program almost into a full file browser.
joachim99@11: </para><para>
joachim99@11: I hope KDiff3 works for you too. Have fun!
joachim99@11: </para><para>
joachim99@11: Joachim Eibl (2003)
joachim99@11: </para>
joachim99@11: </sect1>
joachim99@11: 
joachim99@11: <sect1 id="screenshots"><title>Screenshots and Features</title>
joachim99@11: <para>This screenshot shows the difference between two text files</para>
joachim99@11: <para>(Using an early version of KDiff3):</para>
joachim99@11: <screenshot><mediaobject>
joachim99@11:    <imageobject><imagedata fileref="screenshot_diff.png" format="PNG"/></imageobject>
joachim99@11: </mediaobject></screenshot>
joachim99@11: 
joachim99@11: <para>
joachim99@11:    3-way-merging is fully supported. This is useful if two people change code independently.
joachim99@11:    The original file (the base) is used to help KDiff3 to automatically select the correct
joachim99@11:    changes.
joachim99@11:    The merge-editor below the diff-windows allows you to solve conflicts, while showing you the output you will get.
joachim99@11:    You can even edit the output.
joachim99@11:    This screenshot shows three input files being merged:
joachim99@11: </para><para>
joachim99@11: <screenshot><mediaobject>
joachim99@11:    <imageobject><imagedata fileref="screenshot_merge.png" format="PNG"/></imageobject>
joachim99@11: </mediaobject></screenshot>
joachim99@11: </para>
joachim99@11: 
joachim99@11: <para id="dirmergebigscreenshot">KDiff3 also helps you to compare and merge complete directories.
joachim99@11: This screenshot shows KDiff3 during a directory merge:
joachim99@11: </para><para>
joachim99@11: <screenshot><mediaobject>
joachim99@11:    <imageobject><imagedata fileref="dirmergebig.png" format="PNG"/></imageobject>
joachim99@11: </mediaobject></screenshot>
joachim99@11: </para>
joachim99@11: </sect1>
joachim99@11: 
joachim99@11: <sect1 id="features"><title>More Features</title>
joachim99@11: <sect2><title> Line-By-Line And Char-By-Char Diff-Viewer</title>
joachim99@11: <para>By using the possiblities of a graphical color display KDiff3 shows
joachim99@11:    exactly what the difference is. When you have to do many code-reviews, you will like this.
joachim99@11: </para>
joachim99@11: <screenshot><mediaobject>
joachim99@11:    <imageobject><imagedata fileref="letter_by_letter.png" format="PNG"/></imageobject>
joachim99@11: </mediaobject></screenshot>
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: <sect2><title> See White-Space Differences At One Glance</title>
joachim99@11: <para>Spaces and tabs that differ appear visibly. When lines differ only
joachim99@11:    in  the  amount of white space this can be seen at one look in the summary
joachim99@11:    column on the left side. (No more worries when people change the indentation.)
joachim99@11: </para>
joachim99@11: <screenshot><mediaobject>
joachim99@11:    <imageobject><imagedata fileref="white_space.png" format="PNG"/></imageobject>
joachim99@11: </mediaobject></screenshot>
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: <sect2><title> Triple-Diff</title>
joachim99@11: <para> Analyze three files and see where they differ.
joachim99@11: </para><para>
joachim99@11:    The left/middle/right windows are named A/B/C and have the blue/green/magenta
joachim99@11:    color respectively.
joachim99@11: </para><para>
joachim99@11:    If one file is the same and one file is different on a line then the
joachim99@11:    color   shows which file is different. The red color means that both other
joachim99@11:    files  are different.
joachim99@11: </para>
joachim99@11: <screenshot><mediaobject>
joachim99@11:    <imageobject><imagedata fileref="triple_diff.png" format="PNG"/></imageobject>
joachim99@11: </mediaobject></screenshot>
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: <sect2><title> Comfortable Merge Of Two Or Three Input Files</title>
joachim99@11: <para> KDiff3 can be used to merge two or three input files and automatically
joachim99@11:    merges as much as possible. The result is presented in an editable window
joachim99@11:    where most conflicts can be solved with a single mouseclick: Select the
joachim99@11:    buttons  A/B/C from the button-bar to select the source that should be used.
joachim99@11:    You can  also select more than one source. Since this output window is an
joachim99@11:    editor even  conflicts which need further corrections can be solved here without
joachim99@11:    requiring  another tool.
joachim99@11: </para>
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: <sect2><title> And ...</title>
joachim99@11: <itemizedlist>
joachim99@11:    <listitem><para> Fast navigation via buttons.</para></listitem>
joachim99@11:    <listitem><para> A mouse-click into a summary column sync's all windows to show the same position.</para></listitem>
joachim99@11:    <listitem><para> Select and copy from any window and paste into the merge result window.</para></listitem>
joachim99@11:    <listitem><para> Overview column that shows where the changes and conflicts are.</para></listitem>
joachim99@11:    <listitem><para> The colors are adjustable to your specific preferences.</para></listitem>
joachim99@11:    <listitem><para> Adjustable Tab size.</para></listitem>
joachim99@11:    <listitem><para> Option to insert spaces instead of tabs.</para></listitem>
joachim99@11:    <listitem><para> Open files comfortably via dialog or specify files on the command line.</para></listitem>
joachim99@11:    <listitem><para> Search for strings in all text windows. Find (Ctrl-F) and Find Next (F3)</para></listitem>
joachim99@11:    <listitem><para> Show the line numbers for each line. </para></listitem>
joachim99@11:    <listitem><para> Paste clipboard or drag text into a diff input window.</para></listitem>
joachim99@11:    <listitem><para> Networktransparency via KIO.</para></listitem>
joachim99@11:    <listitem><para> ...</para></listitem>
joachim99@11: </itemizedlist>
joachim99@11: </sect2>
joachim99@11: </sect1>
joachim99@11: </chapter>
joachim99@11: 
joachim99@11: <chapter id="documentation"><title>Documentation of File Comparison And Merge</title>
joachim99@11: 
joachim99@11: <sect1 id="commandline"><title>Command-Line Options</title>
joachim99@11: 
joachim99@11: <sect2><title>Comparing 2 files: </title>
joachim99@11: <screen>
joachim99@11:    <command>kdiff3</command> <replaceable>file1 file2</replaceable>
joachim99@11: </screen>
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: <sect2><title>Merging 2 files: </title>
joachim99@11: <screen>
joachim99@11:    <command>kdiff3</command> <replaceable>file1 file2</replaceable> -m
joachim99@11:    <command>kdiff3</command> <replaceable>file1 file2</replaceable> -o <replaceable>outputfile</replaceable>
joachim99@11: </screen>
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: <sect2><title>Comparing 3 files: </title>
joachim99@11: <screen>
joachim99@11:    <command>kdiff3</command> <replaceable>file1 file2 file3</replaceable>
joachim99@11: </screen>
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: <sect2><title>Merging 3 files: </title>
joachim99@11: <screen>
joachim99@11:    <command>kdiff3</command> <replaceable>file1 file2 file3</replaceable> -m
joachim99@11:    <command>kdiff3</command> <replaceable>file1 file2 file3</replaceable> -o <replaceable>outputfile</replaceable>
joachim99@11: </screen>
joachim99@11: <para>
joachim99@11:    Note that <replaceable>file1</replaceable> will be treated as
joachim99@11:    base of <replaceable>file2</replaceable> and
joachim99@11:    <replaceable>file3</replaceable>.
joachim99@11: </para>
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: <sect2><title>Special case: Files with the same name </title>
joachim99@11: <para>
joachim99@11: If all files have the same name but are in different directories, you can
joachim99@11: reduce typework by specifying the filename only for the first file. E.g.:
joachim99@11: </para>
joachim99@11: <screen>
joachim99@11:    <command>kdiff3</command> <replaceable>dir1/filename dir2 dir3</replaceable>
joachim99@11: </screen>
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: <sect2><title>Commandline for starting a directory comparison or merge: </title>
joachim99@11: <para>This is very similar, but now it's about directories.</para>
joachim99@11: <screen>
joachim99@11:    <command>kdiff3</command> <replaceable>dir1 dir2</replaceable>
joachim99@11:    <command>kdiff3</command> <replaceable>dir1 dir2</replaceable> -o <replaceable>destdir</replaceable>
joachim99@11:    <command>kdiff3</command> <replaceable>dir1 dir2 dir3</replaceable>
joachim99@11:    <command>kdiff3</command> <replaceable>dir1 dir2 dir3</replaceable> -o <replaceable>destdir</replaceable>
joachim99@11: </screen>
joachim99@11: <para>For directory comparison and merge you can continue to read <link linkend="dirmerge">here</link>.</para>
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: <sect2><title>For more information on command line options use: </title>
joachim99@11: <screen>
joachim99@11:    <command>kdiff3</command> --help
joachim99@11: </screen>
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: </sect1>
joachim99@11: 
joachim99@11: <sect1 id="opendialog"><title>Open-Dialog</title>
joachim99@11: <para>
joachim99@11:    Since many input files must be selectable, the program has a special open dialog:
joachim99@11: </para>
joachim99@11: <screenshot><mediaobject>
joachim99@11: <imageobject><imagedata fileref="open_dialog.png" format="PNG"/></imageobject>
joachim99@11: </mediaobject></screenshot>
joachim99@11: <para>
joachim99@11:    The open dialog allows to edit the filenames by hand, selecting a file
joachim99@11:    via  the file-browser ("File...") or allows to choose recent files from
joachim99@11:    the drop-down lists. If you open the dialog again, then the current names
joachim99@11:    still remain there. The third input file is not required. If the
joachim99@11:    entry   for "C" remains empty, then only a two file diff analysis will be
joachim99@11:    done.
joachim99@11: </para><para>
joachim99@11:    You can also select a directory via "Dir...". If for A a directory is specified
joachim99@11:    then a directory-comparison/merge starts. If A specifies a file but B, C or
joachim99@11:    the output specify a directory, then KDiff3 uses the filename from A in the
joachim99@11:    specified directories.
joachim99@11: </para><para>
joachim99@11:    If "Merge" is selected, then the "Output"-line becomes editable. But it
joachim99@11:    is not required to specify the output filename immediately. You can also
joachim99@11:    postpone this until saving.
joachim99@11: </para><para>
joachim99@11:    The "Configure..."-button opens the options-dialog, so that you can set
joachim99@11:    the options before running the analysis.
joachim99@11: </para>
joachim99@11: </sect1>
joachim99@11: 
joachim99@11: <sect1 id="pasteinput"><title>Paste and Drop Input</title>
joachim99@11: <para>
joachim99@11:    Sometimes you want to compare parts of a text that is not an own file. KDiff3 also
joachim99@11:    allows you to paste text from the clipboard into the diff input window that has the focus.
joachim99@11:    The diff analysis happens immediately then.
joachim99@11:    In the open dialog you need not specify files then, but just close it via "Cancel".
joachim99@11: </para><para>
joachim99@11:    You can also use drag and drop: Drag a file from a file manager
joachim99@11:    or selected text from an editor and drop it onto a diff input window.
joachim99@11: </para><para>
joachim99@11:    What's the idea? Sometimes a file contains two similar functions, but checking how similar
joachim99@11:    they really are is a big effort if you first must create two files and then load them. Now
joachim99@11:    you can simply copy, paste and compare the relevant sections.
joachim99@11: </para><para>
joachim99@11:    Note: Currently you can't drag anything from KDiff3. Only dropping in the diff input
joachim99@11:    is supported.
joachim99@11: </para><para>
joachim99@11:    Warning: Some editors still interpret the drag and drop into another program like cut
joachim99@11:    (instead of copy) and paste. Your original data might be lost then.
joachim99@11: </para>
joachim99@11: </sect1>
joachim99@11: 
joachim99@11: <sect1 id="interpretinginformation"><title>Interpreting The Information In The Input Windows</title>
joachim99@11: <screenshot><mediaobject>
joachim99@11: <imageobject><imagedata fileref="screenshot_diff.png" format="PNG"/></imageobject>
joachim99@11: </mediaobject></screenshot>
joachim99@11: <para>
joachim99@11:    At the top of each text window is its "info line". The info lines of
joachim99@11:    the   input windows contain a letter "A", "B" or "C", the filename and the
joachim99@11:    line   number of the first visible line in the window. (Note that window
joachim99@11:    "C" is  optional.) Each info line appears in a different color. (If the paths
joachim99@11:    are too long to fit, then you can move the mouse onto the info line and
joachim99@11:    a  tooltip will show the complete name.)
joachim99@11: </para><para>
joachim99@11:    The three input windows are assigned the letters "A", "B" and "C".
joachim99@11:    "A"   has  color blue, "B" has green and "C" has magenta. (These are the
joachim99@11:    defaults,   but  can be changed in the Settings-Menu.)
joachim99@11: </para><para>
joachim99@11:    When a difference is detected then the color shows which input file
joachim99@11:    differs.   When both other input files differ then the color used to express
joachim99@11:    this is   red by default ("Conflict color" in the Settings).
joachim99@11:    This colorscheme is especially useful in the case of three input files, which will be
joachim99@11:    seen in the next section (<link linkend="merging">Merging</link>).
joachim99@11: </para><para>
joachim99@11:    Left of each text is the "summary column". If differences occurred on a
joachim99@11:    line then the summary column shows the respective color. For a white-space-only
joachim99@11:    difference the summary is chequered. For programming languages where white
joachim99@11:    space is not so important this is useful to see at one glance if anything
joachim99@11:    of importance was modified. (In C/C++ white space is only interesting within
joachim99@11:    strings, comments, for the preprocessor, and some only very esoteric situations.)
joachim99@11: </para><para>
joachim99@11:    The vertical line separating the summary column and the text is interrupted
joachim99@11:    if the input file had no lines there.
joachim99@11: </para><para>
joachim99@11:    On the right side a "overview"-column is visible left of the vertical scrollbar.
joachim99@11:    It shows the compressed summary column of input "A". All the differences
joachim99@11:    and conflicts are visible at one glance. When only two input windows are
joachim99@11:    used, then all differences appear red here because every difference is
joachim99@11:    also   a conflict. A black rectangle frames the visible part of the inputs.
joachim99@11:    For  very long input files, when the number of input lines is bigger than
joachim99@11:    the height of the overview column in pixels, then several input lines share
joachim99@11:    one overview line. A conflict then has top priority over simple differences,
joachim99@11:    which have priority over no change, so that no difference or conflict is
joachim99@11:    lost here.  By clicking into this overview column the corresponding text
joachim99@11:    will be shown.
joachim99@11: </para>
joachim99@11: </sect1>
joachim99@11: 
joachim99@11: 
joachim99@11: <sect1 id="merging"><title>Merging And The Merge Output Editor Window</title>
joachim99@11: <screenshot><mediaobject>
joachim99@11: <imageobject><imagedata fileref="screenshot_merge.png" format="PNG"/></imageobject>
joachim99@11: </mediaobject></screenshot>
joachim99@11: <para>
joachim99@11:    The merge output editor window (below the diff input windows) also has an info line at the top showing "Output:", the
joachim99@11:    filename   and "[Modified]" if you edited something. Usually it will contain
joachim99@11:    some text  through the automatic merge facilities, but often it will also
joachim99@11:    contain conflicts.
joachim99@11: </para><para>
joachim99@11:    !!! Saving is disabled until all conflicts are resolved !!! (Use the "Go
joachim99@11:    to prev/next unsolved conflicts"-buttons to find the remaining conflicts.)
joachim99@11: </para><para>
joachim99@11:    With only two input files every difference is also a conflict that must
joachim99@11:    be solved manually.
joachim99@11: </para><para>
joachim99@11:    With three input files the first file is treated as base, while the
joachim99@11:    second   and third input files contain modifications. When at any line only
joachim99@11:    either   input B or input C have changed but not both then the changed source
joachim99@11:    will   automatically be selected. Only when B and C have changed on the same
joachim99@11:    lines,   then the tool detects a conflict that must be solved manually.
joachim99@11:    When B and C are the same, but not the same as A, then C is selected.
joachim99@11: </para><para>
joachim99@11:    The merge output editor window also has a summary column on the left. It shows the
joachim99@11:    letter of the input from which a line was selected or nothing if all three
joachim99@11:    sources where equal on a line. For conflicts it shows a questionmark "?"
joachim99@11:    and the line shows "&lt;Merge Conflict&gt;", all in red. Because solving
joachim99@11:    conflicts  line by line would take very long, the lines are grouped into
joachim99@11:    groups that  have the same difference and conflict characteristics.
joachim99@11:    But only-white-space-conflicts are separated from non-white-space-conflicts
joachim99@11:    in order to ease the merging of files were the indentation changed for many
joachim99@11:    lines.
joachim99@11: </para><para>
joachim99@11:    When clicking into  the summary column with the left mouse button in either
joachim99@11:    window then the group belonging to that line will be selected in all windows
joachim99@11:    and the beginning of that group will be shown. (This might involve an automatic
joachim99@11:    position jump in the windows if the beginning of a group is not visible.)
joachim99@11:    This group then becomes the "current group". It is highlighted with the
joachim99@11:    "Current range (diff) background color" and
joachim99@11:    a black bar appears on the left side of the text.
joachim99@11: </para><para>
joachim99@11:    Note the input selector buttons containing the letters "A", "B" and
joachim99@11:    "C"   in the button bar below the menu bar. When clicking on either input
joachim99@11:    selector   button, the lines from that input will be added at the end of the
joachim99@11:    selected   group if that group didn't contain that source before. Otherwise
joachim99@11:    the lines   from that input will be removed.
joachim99@11: </para><para>
joachim99@11:    Besides, you can directly edit any line. The summary column will show "m"
joachim99@11:    for every line that was modified.
joachim99@11: </para><para>
joachim99@11:    Sometimes, when a line is removed either by automatic merge or by editing
joachim99@11:    and no other lines remain in that group, then the text &lt;No src line&gt;
joachim99@11:    will appear in that line. This is just a placeholder for the group for
joachim99@11:    when  you might change your mind and select some source again. This text won't
joachim99@11:    appear in the saved file or in any selections you want to copy and paste.
joachim99@11: </para><para>
joachim99@11:    The text "&lt;Merge Conflict&gt;" will appear in the clipboard if you
joachim99@11:    copy and   paste some text containing such a line. But still be careful to
joachim99@11:    do so.
joachim99@11: </para><para>
joachim99@11:    The "Merge" menu contains some actions that let you select "A", "B" or
joachim99@11:    "C" everywhere. When you select "Automatically solve simple conflicts" then
joachim99@11:    KDiff3 restarts the merge and solves as many conflicts as it can. "Set deltas
joachim99@11:    to conflicts" does the opposite: Even simple conflicts have to be solved
joachim99@11:    manually then. For all these actions the manual selections that happened
joachim99@11:    before are lost. (KDiff3 will tell you so, before proceeding.)
joachim99@11: </para>
joachim99@11: </sect1>
joachim99@11: 
joachim99@11: <sect1 id="navigation"><title>Navigation And Editing</title>
joachim99@11: <para>
joachim99@11:    Much navigation will be done with the scroll bars and the mouse but
joachim99@11:    you  can also navigate with the keys. If you click into either window then
joachim99@11:    you  can use the cursor buttons left, right, up, down, page up, page down,
joachim99@11:    home,  end, ctrl-home, ctrl-end as you would in other programs. The overview-column
joachim99@11:    next to the vertical scroll bar of the input files can also be used  for
joachim99@11:    navigating by clicking into it.
joachim99@11: </para><para>
joachim99@11:    You can also use the wheel mouse to scroll up and down.
joachim99@11: </para><para>
joachim99@11:    In the merge output editor you can also use the other keys for editing.
joachim99@11:    You can toggle between insert and overwrite mode with the insert key. (Default
joachim99@11:    is insert-mode.)
joachim99@11: </para><para>
joachim99@11:    A left-mouse-button-click into any summary column will synchronise all
joachim99@11:    windows to show the beginning of the same group of lines (as explained
joachim99@11:    in section <link linkend="merging">"Merging"</link>).
joachim99@11: </para><para>
joachim99@11:    The button bar also contains seven navigation buttons with which you can
joachim99@11:    jump to the current/first/last difference, to the next/previous difference
joachim99@11:    (ctrl-down/ctrl-up), to the next/previous conflict (ctrl-pgdown/ctrl-pgup),
joachim99@11:    or to the next/previous unsolved conflict. Note that for KDiff3 a "conflict"
joachim99@11:    that was not automatically solved at the start of the merge stays a "conflict"
joachim99@11:    even if it is solved. Hence the necessity to distinguish "unsolved conflicts".
joachim99@11: </para><para>
joachim99@11:    There also is a button "Automatically go to next unsolved conflict after
joachim99@11:    source selection" (Auto-Advance). If you enable this, then, when one source
joachim99@11:    is selected, then KDiff3 will jump to and select the next unsolved conflict
joachim99@11:    automatically. This can help when you always want to choose one source only.
joachim99@11:    When you need both sources, or you want to edit after selecting, then you
joachim99@11:    probably want to switch this off. Before proceeding to the next unsolved conflict
joachim99@11:    KDiff3 shows you the effect of your choice for a short time. This delay is
joachim99@11:    adjustable in the Diff- &amp; Merge-Settings: You can
joachim99@11:    specify the "Auto-Advance delay" in milli seconds between 0 and 2000. Hint:
joachim99@11:    Tired of many clicks? - Use a small Auto-Advance-delay and the shortcuts
joachim99@11:    Ctrl-1/2/3 to select A/B/C for many conflicts.
joachim99@11: </para>
joachim99@11: </sect1>
joachim99@11: 
joachim99@11: <sect1 id="selections"><title>Select, Copy And Paste</title>
joachim99@11: <para>
joachim99@11:    The input windows don't show a cursor, so selections must be made
joachim99@11:    with   the mouse by clicking with the left mouse button at the start, holding
joachim99@11:    down   the mousebutton and moving to the end, where you release the mouse
joachim99@11:    button   again. You can also select a word by double clicking it. In the merge
joachim99@11:    output   editor you can also select via the keyboard by holding the "shift"-button
joachim99@11:    and navigation with the cursor keys.
joachim99@11: </para><para>
joachim99@11:    To copy to the clipboard you must press the "Copy"-button (Ctrl-C or Ctrl-Insert).
joachim99@11:    But   there exists an option "Auto Copy Selection". If this is enabled,
joachim99@11:    then  whatever   you select is copied immediately and you don't need to explicitely
joachim99@11:    copy. But pay attention when using this because the contents of the clipboard
joachim99@11:    might   then be destroyed accidentally.
joachim99@11: </para><para>
joachim99@11:    "Cut" (Ctrl-X or Shift-Delete) copies to the clipboard and deletes the
joachim99@11:    selected text and   "Paste" (Ctrl-V or Shift-Insert) inserts the text in
joachim99@11:    the clipboard at the cursorposition  or over the current selection.
joachim99@11: </para>
joachim99@11: </sect1>
joachim99@11: 
joachim99@11: <sect1 id="saving"><title>Saving</title>
joachim99@11: <para>
joachim99@11:    Saving will only be allowed, when all conflicts were solved. If the file
joachim99@11:    already exists and the "Backup files"-option is enabled then the existing
joachim99@11:    file will be renamed with an ".orig"-extension, but if such a file exists
joachim99@11:    it will be deleted. When you exit or start another diff-analysis and data
joachim99@11:    wasn't saved yet, then KDiff3 will ask if you want to save, cancel or proceed
joachim99@11:    without saving. (KDiff3 does not catch any signals. So if you "kill" KDiff3
joachim99@11:    then your data will be lost.)
joachim99@11: </para><para>
joachim99@11:    Line endings are saved according to the normal method on the underlying
joachim99@11:    operating system. For Unices each line ends with an linefeed-character "\n",
joachim99@11:    while for Win32-based systems each line ends with a carriage-return + a linefeed
joachim99@11:    "\r\n". KDiff3 does not preserve the line-endings of the input files, which
joachim99@11:    also means that you shouldn't use KDiff3 with binary files.
joachim99@11: </para>
joachim99@11: </sect1>
joachim99@11: 
joachim99@11: <sect1 id="find"><title>Finding Strings</title>
joachim99@11: <para>
joachim99@11:    You can search for a string in any text-window of KDiff3. The "Find ..."-command
joachim99@11:    (Ctrl-F) in the Edit-menu opens a dialog that lets you specify the string
joachim99@11:    to search for. You can also select the windows which should be searched.
joachim99@11:    Searching will always start at the top. Use the "Find Next"-command (F3)
joachim99@11:    to proceed to the next occurance. If you select to search several windows then the first
joachim99@11:    window will be searched from top to bottom before the search starts in the next
joachim99@11:    window at the top again, etc.
joachim99@11: </para>
joachim99@11: </sect1>
joachim99@11: 
joachim99@11: 
joachim99@11: <sect1 id="options"><title>Options</title>
joachim99@11: <para>
joachim99@11:    Options and the recent-file-list will be saved when you exit the program,
joachim99@11:    and reloaded when you start it. (Menu Settings->Configure KDiff3 ...)
joachim99@11: </para>
joachim99@11: <sect2><title>Font</title>
joachim99@11: <para>
joachim99@11:    Select a fixed width font. (On some systems this dialog will also
joachim99@11:    present    variable width fonts, but you should not use them.)
joachim99@11: </para>
joachim99@11: <variablelist>
joachim99@11:    <varlistentry><term><emphasis>Italic Font for Deltas:</emphasis></term><listitem><para> If you select this, then text differences
joachim99@11:        will be drawn with the italic version of the selected font. If the font
joachim99@11:        doesn't  support italic, then this does nothing.</para>
joachim99@11:    </listitem></varlistentry>
joachim99@11: </variablelist>
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: <sect2><title>Colors</title>
joachim99@11: <variablelist>
joachim99@11:    <varlistentry><term><emphasis>Foreground color:</emphasis></term><listitem><para> Usually black. </para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Background color:</emphasis></term><listitem><para> Usually white. </para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Diff Background color:</emphasis></term><listitem><para> Usually light gray. </para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Color A:</emphasis></term><listitem><para> Usually dark blue. </para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Color B:</emphasis></term><listitem><para> Usually dark green. </para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Color C:</emphasis></term><listitem><para> Usually dark magenta. </para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Conflict Color:</emphasis></term><listitem><para> Usually red.</para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Current range background color:</emphasis></term><listitem><para> Usually light yellow.</para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Current range diff background color:</emphasis></term><listitem><para> Usually dark yellow.</para></listitem></varlistentry>
joachim99@11: </variablelist>
joachim99@11: <para>
joachim99@11:    On systems with only 16 or 256 colors some colors are not available in pure
joachim99@11:    form. On such systems the "Defaults"-button will choose a pure color.
joachim99@11: </para>
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: <sect2><title>Editor Settings</title>
joachim99@11: <variablelist>
joachim99@11:    <varlistentry><term><emphasis>Tab inserts spaces:</emphasis></term><listitem><para> If this is disabled and you press the
joachim99@11:       tabulator key,   a tab-character is inserted, otherwise the appropriate
joachim99@11:       amount  of characters   is inserted.</para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>   Tab size:</emphasis></term><listitem><para> Can be adjusted for your specific needs. Default is 8. </para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>   Auto indentation:</emphasis></term><listitem><para> When pressing Enter or Return the indentation
joachim99@11:       of the previous  line is used for the new line. </para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>   Auto copy selection:</emphasis></term><listitem><para> Every selection is immediately copied
joachim99@11:       to the clipboard   when active and you needn't explicitely copy it. </para></listitem></varlistentry>
joachim99@11: </variablelist>
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: <sect2><title>Diff &amp; Merge Settings</title>
joachim99@11: <para>
joachim99@11:    When comparing files, KDiff3 first it tries to match lines that are equal
joachim99@11:    in all input files. Only during this step it might ignore white space. The
joachim99@11:    second step compares each line. In this step white space will not be ignored.
joachim99@11:    Also during the merge white space will not be ignored.
joachim99@11: </para>
joachim99@11: 
joachim99@11: <variablelist>
joachim99@11:    <varlistentry><term><emphasis>Ignore white space:</emphasis></term><listitem><para> Default is on. White space will be
joachim99@11:       ignored  in the first  part of the analysis in which the line matching is
joachim99@11:       done. In  the result the  white space differences will be shown nevertheless.
joachim99@11:    </para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Preserve Carriage Return:</emphasis></term><listitem><para> Some editors (on some systems) save
joachim99@11:       carriage return '\r' and linefeed '\n'-characters at the end of line, while
joachim99@11:       others will only save the linefeed '\n'. Usually KDiff3 ignores the carriage
joachim99@11:       return, but then files that don't have equal sizes, look equal in side by
joachim99@11:       side comparison. When this option is on, then the carriage return characters
joachim99@11:       are made visible but are treated as white space. This option must be off
joachim99@11:       during a merge. Default is off.</para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Ignore numbers:</emphasis></term><listitem><para> Default is off. Number characters ('0'-'9', '.', '-')
joachim99@11:       will be ignored  in the first  part of the analysis in which the line matching is
joachim99@11:       done. In the result the differences will be shown nevertheless, but they are treated
joachim99@11:       as white space.
joachim99@11:    </para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Convert to Upper Case:</emphasis></term><listitem><para>  Default is off. Converts the input to upper case
joachim99@11:       while reading. Hence the comparison is not case sensitive. Take care during merging
joachim99@11:       because the case information will be lost in the merge-result too.
joachim99@11:    </para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Preprocessor-Command:</emphasis></term><listitem><para>
joachim99@11:       When any file is read, it will be piped through this external command.
joachim99@11:       The output of this command will be visible instead of the original file.
joachim99@11:       You can write your own preprocessor that fulfills your specific needs.
joachim99@11:       Use this to cut away disturbing parts of the file, or to automatically
joachim99@11:       correct the indentation etc.
joachim99@11:    </para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Line-Matching Preprocessor-Command:</emphasis></term><listitem><para>
joachim99@11:       When any file is read, it will be piped through this external command. If
joachim99@11:       a preprocessor-command (see above) is also specified, then the output of the
joachim99@11:       preprocessor is the input of the line-matching preprocessor.
joachim99@11:       The output will only be used during the line matching phase of the analysis.
joachim99@11:       You can write your own preprocessor that fulfills your specific needs.
joachim99@11:       Each input line must have a corresponding output line.
joachim99@11:    </para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Use external diff:</emphasis></term><listitem><para> If you have an external diff-tool (e.g. GNU-diff)
joachim99@11:       you can use it for the line matching phase. For some complicated files this
joachim99@11:       might be better than the internal algorithm of KDiff3.
joachim99@11:    </para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Try Hard:</emphasis></term><listitem><para> Passes the "--minimal"-option to the external diff
joachim99@11:       tool, which then will try hard to find an even smaller delta. This will probably
joachim99@11:       be effective for complicated and big files. And slow for very big files.
joachim99@11:    </para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Ignore trivial matches:</emphasis></term><listitem><para> Default is on. When trivial lines
joachim99@11:       match after an  difference, this will be ignored and the search for a nontrivial
joachim99@11:       matching  line continues. This improves the results for inputs with empty
joachim99@11:       lines and  lines containing only a open or close-brace character, which is
joachim99@11:       often the  case for C/C++-programs.
joachim99@11:    </para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Max search length:</emphasis></term><listitem><para> Searching for a match is aborted after this
joachim99@11:       number of lines. The diff might fail for small values but take too long
joachim99@11:       for  big values. Default is 1000.
joachim99@11:    </para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Auto Advance Delay (ms):</emphasis></term><listitem><para> When in auto-advance-mode this setting specifies
joachim99@11:       how long to show the result of the selection before jumping to the next unsolved
joachim99@11:       conflict.
joachim99@11:    </para></listitem></varlistentry>
joachim99@11: </variablelist>
joachim99@11: 
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: <sect2><title>Directory Merge</title>
joachim99@11: <para>
joachim99@11:    These options are concerned with scanning the directory and handling the
joachim99@11:    merge: See the <link linkend="dirmergeoptions">Directory Comparison/Merge
joachim99@11:    Docs</link> for details.
joachim99@11: </para><para>
joachim99@11: Yet there is one option here that is also relevant for saving single files:
joachim99@11: </para>
joachim99@11: <variablelist>
joachim99@11:    <varlistentry><term><emphasis>Backup files:</emphasis></term><listitem><para> When a file is saved and an older version already
joachim99@11:       exists, then the original version will be renamed with an ".orig" extension.
joachim99@11:       If an old backup file with ".orig" extension already exists then this will
joachim99@11:       be deleted without backup.
joachim99@11:    </para></listitem></varlistentry>
joachim99@11: </variablelist>
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: <sect2><title>Miscellaneous</title>
joachim99@11: <para>(These options and actions are available in menus or the buttonbar.)</para>
joachim99@11: <variablelist>
joachim99@11:   <varlistentry><term><emphasis>Show line numbers:</emphasis></term><listitem><para> You can select if line numbers should be
joachim99@11:      shown for the input files.</para></listitem></varlistentry>
joachim99@11:   <varlistentry><term><emphasis>Show space and tabulator characters for differences:</emphasis></term><listitem><para> Sometimes
joachim99@11:      the visible spaces and tabs are disturbing. You can turn this off.</para></listitem></varlistentry>
joachim99@11:   <varlistentry><term><emphasis>Show Window A/B/C:</emphasis></term><listitem><para> Sometimes you want to use the space on
joachim99@11:       the screen better for long lines. Hide the windows that are not important.
joachim99@11:       (In the Windows-menu.)</para></listitem></varlistentry>
joachim99@11:   <varlistentry><term><emphasis>Toggle Split Orientation:</emphasis></term><listitem><para>
joachim99@11:       Switch between diff windows shown next to each other (A left of B left of C) or above
joachim99@11:       each other (A above B above C). This should also help for long lines. (In the Windows-menu.)
joachim99@11:       </para></listitem></varlistentry>
joachim99@11:   <varlistentry><term><emphasis>Start a merge quickly:</emphasis></term><listitem><para> Sometimes you are viewing the deltas
joachim99@11:       and decide to merge. <inlinemediaobject><imageobject><imagedata fileref="merge_current.png" format="PNG"/></imageobject></inlinemediaobject>
joachim99@11:       "Merge current file" in the Directory-menu also works if you only compare
joachim99@11:       two files. A single click starts the merge and uses the filename of the last
joachim99@11:       input-file as the default output filename. (When this is used to restart
joachim99@11:       a merge, then the output filename will be preserved.)</para></listitem></varlistentry>
joachim99@11: </variablelist>
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: <sect2 id="shortcuts"><title>Configuring Keyboard-Shortcuts</title>
joachim99@11: <para>
joachim99@11:    Currently only the KDE-version supports user-configurable keyboard-shortcuts.
joachim99@11:    (Menu Settings->Configure Shortcuts...)
joachim99@11: </para>
joachim99@11: </sect2>
joachim99@11: </sect1>
joachim99@11: </chapter>
joachim99@11: 
joachim99@11: 
joachim99@11: <chapter id="dirmerge"><title>Directory Comparison and Merge with KDiff3</title>
joachim99@11: <sect1 id="dirmergeintro"><title>Introduction</title>
joachim99@11: <para>
joachim99@11:    Often programmers must modify many files in a directory to achieve their
joachim99@11:    purpose. For this KDiff3 also lets you compare and merge complete directories
joachim99@11:    recursively!
joachim99@11: </para><para>
joachim99@11:    Even though comparing and merging directories seems to be quite obvious,
joachim99@11:    there are several details that you should know about. Most important is of
joachim99@11:    course the fact that now many files might be affected by each operation.
joachim99@11:    If you don't have backups of your original data, then it can be very hard
joachim99@11:    or even impossible to return to the original state. So before starting a merge,
joachim99@11:    make sure that your data is safe, and going back is possible. If you make
joachim99@11:    an archive or use some version control system is your decision, but even
joachim99@11:    experienced programmers and integrators need the old sources now and then.
joachim99@11:    And note that even though I (the author of KDiff3) try to do my best, I can't
joachim99@11:    guarantee that there are no bugs. According to the GNU-GPL there is NO WARRANTY
joachim99@11:    whatsoever for this program. So be humble and always keep in mind:
joachim99@11: </para>
joachim99@11: <blockquote><para>
joachim99@11:    <emphasis>To err is human, but to really mess things up you need a computer.</emphasis>
joachim99@11: </para></blockquote>
joachim99@11: <para>
joachim99@11: So this is what this program can do for you: KDiff3 ...
joachim99@11: </para>
joachim99@11: <itemizedlist>
joachim99@11:      <listitem><para>... reads and compares two or three directories recursively,</para></listitem>
joachim99@11:      <listitem><para>... takes special care of symbolic links,</para></listitem>
joachim99@11:      <listitem><para>... lets you browse files on mouse double click,</para></listitem>
joachim99@11:      <listitem><para>... for each item proposes a merge operation, which you can change
joachim99@11:                          before starting the directory merge,</para></listitem>
joachim99@11:      <listitem><para>... lets you simulate the merge and lists the actions that would
joachim99@11:                          take  place, without actually doing them,</para></listitem>
joachim99@11:      <listitem><para>... lets you really do the merge, and lets you interact whenever
joachim99@11:                          manual interaction is needed,</para></listitem>
joachim99@11:      <listitem><para>... lets you continue the merge after manual interaction with key F5,</para></listitem>
joachim99@11:      <listitem><para>... optionally creates backups, with the ".orig" extension,</para></listitem>
joachim99@11:      <listitem><para>...</para></listitem>
joachim99@11: </itemizedlist>
joachim99@11: </sect1>
joachim99@11: 
joachim99@11: <sect1 id="startingdirmerge"><title>Starting Directory Comparison Or Merge</title>
joachim99@11: <para>
joachim99@11:    This is very similar to the single file merge and comparison. You just
joachim99@11:    have  to specify directories on the command line or in the file-open
joachim99@11:    dialog.
joachim99@11: </para>
joachim99@11: <sect2><title>Compare/Merge two directories: </title>
joachim99@11: <screen>
joachim99@11:    <command>kdiff3</command> <replaceable>dir1 dir2</replaceable>
joachim99@11:    <command>kdiff3</command> <replaceable>dir1 dir2</replaceable> -o <replaceable>destdir</replaceable>
joachim99@11: </screen>
joachim99@11: <para>
joachim99@11:    If no destination directory is specified, then KDiff3 will use <replaceable>dir2</replaceable>.
joachim99@11: </para>
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: <sect2><title>Compare/Merge three directories: </title>
joachim99@11: <screen>
joachim99@11:    <command>kdiff3</command> <replaceable>dir1 dir2 dir3</replaceable>
joachim99@11:    <command>kdiff3</command> <replaceable>dir1 dir2 dir3</replaceable> -o <replaceable>destdir</replaceable>
joachim99@11: </screen>
joachim99@11: <para>
joachim99@11:    When three directories are merged then <replaceable>dir1</replaceable>
joachim99@11:    is used as the base for the merge.
joachim99@11:    If no destination directory is specified, then KDiff3 will use <replaceable>dir3</replaceable>
joachim99@11:    as the  destination directory for the merge.
joachim99@11: </para>
joachim99@11: 
joachim99@11: <para>
joachim99@11:    Note that only the comparison starts automatically, not the merge. For this you first must
joachim99@11:    select a menu entry or the key F5. (More details later.)
joachim99@11: </para>
joachim99@11: </sect2>
joachim99@11: </sect1>
joachim99@11: 
joachim99@11: <sect1 id="dirmergevisible"><title>Visible Information</title>
joachim99@11: <para>
joachim99@11:    While reading the directories a message-box appears that informs you of
joachim99@11:    the progress. If you abort the directory scan, then only files that have
joachim99@11:    been  compared until then will be listed.
joachim99@11: </para><para>
joachim99@11:    When the directory scan is complete then KDiff3 will show a listbox with
joachim99@11:    the results left, ...
joachim99@11: </para>
joachim99@11: <screenshot><mediaobject>
joachim99@11: <imageobject><imagedata fileref="dirbrowser.png" format="PNG"/></imageobject> <!--alt="Image of the directory browser."-->
joachim99@11: </mediaobject></screenshot>
joachim99@11: <para>
joachim99@11:    ... and details about the currently selected item on the right:
joachim99@11: </para>
joachim99@11: <screenshot><mediaobject>
joachim99@11: <imageobject><imagedata fileref="iteminfo.png" format="PNG"/></imageobject>
joachim99@11:    <!--alt="Image with information about the selected item."-->
joachim99@11: </mediaobject></screenshot>
joachim99@11: 
joachim99@11: <sect2 id="name"><title>The Name Column</title>
joachim99@11: <para>
joachim99@11:    Each file and directory that was found during the scan is shown here in
joachim99@11:    a tree. You can select an item by clicking it with the mouse once.
joachim99@11: </para><para>
joachim99@11:    The directories are collapsed by default. You can expand and collapse
joachim99@11:    them by clicking on the "+"/"-" or by double-clicking the item or
joachim99@11:    by using  the left/right-arrow-keys. The "Directory"-menu also contains two
joachim99@11:    actions "Fold all subdirs" and "Unfold all subdirs" with which you can
joachim99@11:    collapse or expand all directories at once.
joachim99@11: </para><para>
joachim99@11:    If you double-click a file item then the file comparison starts and the
joachim99@11:    file-diff-window will appear.
joachim99@11: </para>
joachim99@11: <para>
joachim99@11:    The image in the name column reflects the file type in the first
joachim99@11:    directory  ("A"). It can be one of these:
joachim99@11: </para>
joachim99@11: <itemizedlist>
joachim99@11:      <listitem><para>Normal file</para></listitem>
joachim99@11:      <listitem><para>Normal directory (directory-image)</para></listitem>
joachim99@11:      <listitem><para>Link to a file (file-image with a link arrow)</para></listitem>
joachim99@11:      <listitem><para>Link to a directory (directory-image with a link arrow)</para></listitem>
joachim99@11: </itemizedlist>
joachim99@11: <para>
joachim99@11:    If the file type is different in the other directories, then this is visible
joachim99@11:    in the columns A/B/C and in the window that shows the details about the selected
joachim99@11:    item. Note that for such a case no merge operation can be selected automatically.
joachim99@11:    When starting the merge, then the user will be informed of problems of that
joachim99@11:    kind.
joachim99@11: </para>
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: <sect2 id="coloring"><title>The Columns A/B/C and the Coloring Scheme</title>
joachim99@11: <para>
joachim99@11:    As can be seen in the image above the colors red, green, yellow and black
joachim99@11:    are used in the columns A/B/C.
joachim99@11: </para>
joachim99@11: <itemizedlist>
joachim99@11:      <listitem><para>Black: This item doesn't exist in this directory.</para></listitem>
joachim99@11:      <listitem><para>Green: Newest item.</para></listitem>
joachim99@11:      <listitem><para>Yellow: Older than green, newer than red.</para></listitem>
joachim99@11:      <listitem><para>Red: Oldest item.</para></listitem>
joachim99@11: </itemizedlist>
joachim99@11: <para>
joachim99@11:    But for items that were identical in the comparison their color also is
joachim99@11:    identical even if the age is not.
joachim99@11: </para><para>
joachim99@11:    Directories are considered equal if all items they contain are identical.
joachim99@11:    Then they also will have the same color. But the age of a directory is not
joachim99@11:    considered for its color.
joachim99@11: </para><para>
joachim99@11:    The idea for this coloring scheme I came upon in
joachim99@11:    <ulink url="http://samba.org/cgi-bin/cvsweb/dirdiff">dirdiff</ulink>. The colors
joachim99@11:    resemble the colors of a leaf that is green when new, turns yellow later and red
joachim99@11:    when old.
joachim99@11: </para>
joachim99@11: 
joachim99@11: </sect2><sect2 id="operation"><title>The Operation Column</title>
joachim99@11: <para>
joachim99@11:    After comparing the directories KDiff3 also evaluates a proposal for a
joachim99@11:    merge  operation. This is shown in the "Operation" column. You can modify
joachim99@11:    the operation  by clicking on the operation you want to change. A small menu
joachim99@11:    will popup and allows you to select an operation for that item. This operation
joachim99@11:    will be executed during the merge. It depends on the item and on the merge-mode
joachim99@11:    you are in, what operations are available. The merge-mode is one of
joachim99@11: </para>
joachim99@11: <itemizedlist>
joachim99@11:      <listitem><para>Three directory-merge (A is treated as older base of both).</para></listitem>
joachim99@11:      <listitem><para>Two directory-merge.</para></listitem>
joachim99@11:      <listitem><para>Two directory-sync-mode (activate via option "Synchronize Directories").</para></listitem>
joachim99@11: </itemizedlist>
joachim99@11: <para>
joachim99@11:    In three directory merge the operation proposal will be: If for an item ...
joachim99@11: </para>
joachim99@11: <itemizedlist>
joachim99@11:      <listitem><para>... all three directories are equal: Copy from C</para></listitem>
joachim99@11:      <listitem><para>... A and C are equal but B is not: Copy from B (or if B does not
joachim99@11:                          exist, delete the destination if exists)</para></listitem>
joachim99@11:      <listitem><para>... A and B are equal but C is not: Copy from C (or if C does not
joachim99@11:                          exist, delete the destination if exists)</para></listitem>
joachim99@11:      <listitem><para>... B and C are equal but A is not: Copy from C (or if C does not
joachim99@11:                          exist, delete the destination if exists)</para></listitem>
joachim99@11:      <listitem><para>... only A exists: Delete the destination (if exists)</para></listitem>
joachim99@11:      <listitem><para>... only B exists: Copy from B</para></listitem>
joachim99@11:      <listitem><para>... only C exists: Copy from C</para></listitem>
joachim99@11:      <listitem><para>... A, B and C are not equal: Merge</para></listitem>
joachim99@11:      <listitem><para>... A, B and C don't have the same file type (e.g. A is a directory,
joachim99@11:                          B is a file): "Error: Conflicting File Types". While such items exist the
joachim99@11:                          directory merge cannot start.</para></listitem>
joachim99@11: </itemizedlist>
joachim99@11: <para>
joachim99@11:    In two directory merge the operation proposal will be: If for an item ...
joachim99@11: </para>
joachim99@11: <itemizedlist>
joachim99@11:      <listitem><para>... both directories are equal: Copy from B</para></listitem>
joachim99@11:      <listitem><para>... A exists, but not B: Copy from A</para></listitem>
joachim99@11:      <listitem><para>... B exists, but not A: Copy from B</para></listitem>
joachim99@11:      <listitem><para>... A and B exist but are not equal: Merge</para></listitem>
joachim99@11:      <listitem><para>... A and B don't have the same file type (e.g. A is a directory,
joachim99@11:                          B is a file): "Error: Conflicting File Types". While such items exist the
joachim99@11:                          directory merge cannot start.</para></listitem>
joachim99@11: </itemizedlist>
joachim99@11: <para>
joachim99@11:    Sync-mode is active if only two directories and no explicit destination
joachim99@11:    were specified and if the option "Synchronize directories" is active. KDiff3
joachim99@11:    then selects a default operation so that both directories are the same afterwards.
joachim99@11:    If for an item ...
joachim99@11: </para>
joachim99@11: <itemizedlist>
joachim99@11:      <listitem><para>... both directories are equal: Nothing will be done.</para></listitem>
joachim99@11:      <listitem><para>... A exists, but not B: Copy A to B</para></listitem>
joachim99@11:      <listitem><para>... B exists, but not A: Copy B to A</para></listitem>
joachim99@11:      <listitem><para>... A and B exist, but are not equal: Merge and store the result
joachim99@11:                          in  both directories. (For the user the visible save-filename is B,
joachim99@11:                          but then KDiff3 copies B also to A.)</para></listitem>
joachim99@11:      <listitem><para>... A and B don't have the same file type (e.g. A is a directory,
joachim99@11:                          B is a file): "Error: Conflicting File Types". While such items exist the
joachim99@11:                          directory merge cannot start.</para></listitem>
joachim99@11: </itemizedlist>
joachim99@11: <para>
joachim99@11:    When two directories are merged and the option "Copy newer instead of merging" is selected,
joachim99@11:    then KDiff3 looks at the dates and proposes to choose the newer file. If the files are not
joachim99@11:    equal but have equal dates, then the operation will contain
joachim99@11:    "Error: Dates are equal but files are not." While such items exist the
joachim99@11:    directory merge cannot start.
joachim99@11: </para>
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: <sect2 id="status"><title>The Status Column</title>
joachim99@11: <para>
joachim99@11:    During the merge one file after the other will be processed. The status
joachim99@11:    column will show "Done" for items where the merge operation has succeeded,
joachim99@11:    and other texts if something unexpected happened. When a merge is complete,
joachim99@11:    then you should make a last check to see if the status for all items is
joachim99@11:    agreeable.
joachim99@11: </para>
joachim99@11: </sect2>
joachim99@11: </sect1>
joachim99@11: 
joachim99@11: 
joachim99@11: <sect1 id="dothemerge"><title>Doing A Merge</title>
joachim99@11: <para>
joachim99@11:    When you have made all your operation choices (in all subdirectories too)
joachim99@11:    then you can start the merge.
joachim99@11: </para><para>
joachim99@11:    Be aware that if you didn't specify a destination directory explicitely,
joachim99@11:    then the destination will be "C" in three directory mode, "B" in two directory
joachim99@11:    merge mode, and in sync-mode it will be "A" or/and "B".
joachim99@11: </para><para>
joachim99@11:    If you have specified a destination directory also check that all items
joachim99@11:    that should be in the output, are in the tree. There are some options that
joachim99@11:    cause certain items to be omitted from the directory comparison and merge.
joachim99@11:    Check these options to avoid unpleasant surprises:
joachim99@11: </para>
joachim99@11: <itemizedlist>
joachim99@11:      <listitem><para>"Recursive Directories": If this is off, then items in subdirectories
joachim99@11:                      will not be found.</para></listitem>
joachim99@11:      <listitem><para>"Pattern"/"Anti-Pattern": Include/exclude items that match</para></listitem>
joachim99@11:      <listitem><para>"Exclude Hidden Files"</para></listitem>
joachim99@11:      <listitem><para>"List only Deltas": Files that match in all directories don't appear
joachim99@11:                      in the tree, and hence also not in the destination.</para></listitem>
joachim99@11: </itemizedlist>
joachim99@11: <para>
joachim99@11:    (In the current version, you must do a rescan yourself, after changing
joachim99@11:    options affecting the directory scan.)
joachim99@11: </para><para>
joachim99@11:    If you are satisfied so far, the rest is easy.
joachim99@11: </para><para>
joachim99@11:    In the "Directory"-menu select "Start/Continue directory merge" or press
joachim99@11:    F5 (which is the shortcut).
joachim99@11: </para><para>
joachim99@11:    If  due to conflicting filetypes still some items with invalid operations
joachim99@11:    exist, then a messagebox will appear and these items will be pointed out,
joachim99@11:    so you can select a valid operation for the item.
joachim99@11: </para><para>
joachim99@11:    Otherwise a dialog will appear giving you the options "Do it", "Simulate
joachim99@11:    it" and "Cancel".
joachim99@11: </para>
joachim99@11: <itemizedlist>
joachim99@11:      <listitem><para>Select "Simulate it" if you want to see what would be done without
joachim99@11:                      actually doing it. A verbose list of all operations will be shown.</para></listitem>
joachim99@11:      <listitem><para>Otherwise select "Do it" to really start merging.</para></listitem>
joachim99@11: </itemizedlist>
joachim99@11: <para>
joachim99@11:    Then KDiff3 will run the specified operation for all items. If manual
joachim99@11:    interaction  is required (single file merge), then a merge window will open
joachim99@11:    (<link linkend="dirmergebigscreenshot">see the big screenshot</link>).
joachim99@11: </para><para>
joachim99@11:    When you have finished with a file, again select "Start/Continue directory
joachim99@11:    merge" or the key F5. If you haven't saved yet, a dialog will ask you to
joachim99@11:    do so. Then KDiff3 will continue with the next item.
joachim99@11: </para><para>
joachim99@11:    When KDiff3 encounters an error, it will tell you so and will show the
joachim99@11:    verbose-status-information.  At the bottom of this list, there will be some
joachim99@11:    error messages which should  help you to understand the cause of the problem.
joachim99@11:    When you continue merging (F5 key) KDiff3 will give you the choice to retry
joachim99@11:    or skip the item that caused  the problem. This means that before continuing
joachim99@11:    you can choose another operation  or solve the problem by other means.
joachim99@11: </para><para>
joachim99@11:    When the merge is complete, then KDiff3 will inform you via a message
joachim99@11:    box.
joachim99@11: </para>
joachim99@11: </sect1>
joachim99@11: 
joachim99@11: <sect1 id="dirmergeoptions"><title>Options for Comparing and Merging Directories</title>
joachim99@11: <para>
joachim99@11:    The KDiff3-preferences (menu "Settings"-&gt;"Configure KDiff3") now has
joachim99@11:    a section called "Directory Merge" with these options:
joachim99@11: </para>
joachim99@11: 
joachim99@11: <variablelist>
joachim99@11:    <varlistentry><term><emphasis>Recursive Directories:</emphasis></term><listitem><para> Select whether to search directories
joachim99@11:          recursively.</para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>File Pattern(s):</emphasis></term><listitem><para> Only files that match any pattern here will
joachim99@11:          be put in the tree. More than one pattern may be specified here via using
joachim99@11:          the semicolon ";" as separator. Valid wildcards: '*' and '?'. (e.g. "*.cpp;*.h").
joachim99@11:          Default is "*". Directories need not match this pattern.</para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Anti-Pattern(s):</emphasis></term><listitem><para> Files and directories that match this pattern
joachim99@11:          will be excluded from the tree. More than one pattern may be specified here
joachim99@11:          via using the semicolon ";" as separator. Valid wildcards: '*' and '?'. Default
joachim99@11:          is "*.orig;*.o".</para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Use CVS-Ignore:</emphasis></term><listitem><para>
joachim99@11:          Ignore files and directories that would also be ignored by CVS.
joachim99@11:          Many automatically generated files are ignored by CVS.
joachim99@11:          The big advantage is that this can be directory specific via a local ".cvsignore"-file.
joachim99@11:          (See <ulink url="info:/cvs/cvsignore">info:/cvs/cvsignore</ulink>.)</para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Find Hidden Files and Directories:</emphasis></term><listitem><para> On some filesystems files
joachim99@11:          have an "Hidden"-attribute. On other systems a filename starting with a dot
joachim99@11:          "." causes it to be hidden. This option allows you to decide whether to
joachim99@11:          include  these files in the tree or not. Default is on.</para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Follow File Links:</emphasis></term><listitem><para> For links to files: When disabled, then
joachim99@11:          the symbolic links are compared. When enabled, then the files behind the
joachim99@11:          links are compared. Default is off.</para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Follow Directory Links:</emphasis></term><listitem><para> For links to directories: When disabled,
joachim99@11:          then the symbolic links will be compared. When enabled then the link will
joachim99@11:          be treated like a directory and it will be scanned recursively. (Note that
joachim99@11:          the program doesn't check if the link is "recursive". So for example a directory
joachim99@11:          that contains a link to the directory would cause an infinite loop, and after
joachim99@11:          some time when the stack overflows or all memory is used up, crash the program.)
joachim99@11:          Default is off.</para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>List only deltas:</emphasis></term><listitem><para> Only items that are not equal in all input
joachim99@11:          directories will be listed and only the changed files are visible. Hence
joachim99@11:          files that are equal in all directories won't be copied during a merge and
joachim99@11:          if the destination dir does not contain the files before the merge, you might
joachim99@11:          miss some files later. (This option is likely to be changed in a later version.)
joachim99@11:          Default is off.</para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Trust the modification date:</emphasis></term><listitem><para> If you compare big directories
joachim99@11:          over a slow network, it might be faster to compare the modification dates
joachim99@11:          and file length alone. But this speed improvement comes with the price of
joachim99@11:          a little uncertainty. Use this option with care. Default is off.</para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Synchronize Directories:</emphasis></term><listitem><para> Activates "Sync-Mode" when two directories
joachim99@11:          are compared and no explicit destination directory was specified. In this
joachim99@11:          mode the proposed operations will be chosen so that both source directories
joachim99@11:          are equal afterwards. Also the merge result will be written to both directories.
joachim99@11:          Default is off.</para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Copy newer instead of merging:</emphasis></term><listitem><para> Instead of merging the proposed
joachim99@11:          operation will copy the newer source if changes happened. (Considered unsafe,
joachim99@11:          because it implies that the knowledge, that the other file hasn't been edited
joachim99@11:          too. Check to make sure in every case.) Default is off.</para></listitem></varlistentry>
joachim99@11:    <varlistentry><term><emphasis>Backup files:</emphasis></term><listitem><para> If a file or complete directory is replaced
joachim99@11:          by  another or is deleted then the original version will be renamed with an
joachim99@11:          ".orig"  extension. If an old backup file with ".orig" extension already exists
joachim99@11:          then  this will be deleted without backup. This also affects the normal merging
joachim99@11:          of single files, not only in directory-merge mode. Default is on.</para></listitem></varlistentry>
joachim99@11: </variablelist>
joachim99@11: </sect1>
joachim99@11: 
joachim99@11: <sect1 id="other"><title>Other Functions</title>
joachim99@11: <sect2><title>Split/Full Screen Mode</title>
joachim99@11: <para>
joachim99@11:    Usually the directory merge list view remains visible while a single file
joachim99@11:    is compared or merged. With the mouse you can move the the splitter bar that
joachim99@11:    separates the file list from the text-diff windows. If you don't want this,
joachim99@11:    you can disable "Split Screen View" in the "Directory"-menu. Then you can
joachim99@11:    use "Toggle View" in the "Directory"-menu to switch between the file list
joachim99@11:    and the text-diff view that then occupy the full screen.
joachim99@11: </para>
joachim99@11: </sect2>
joachim99@11: <sect2><title>Comparing or Merging a Single File</title>
joachim99@11: <para>
joachim99@11:    Probably you will prefer a simple double mouse click on a file in order
joachim99@11:    to compare it. Nevertheless there also exists an entry in the "Directory"-menu.
joachim99@11:    You can also directly merge a single file, without starting the directory
joachim99@11:    merge via the "Merge single file" in the "Directory"-Menu. On saving the
joachim99@11:    result, the status will be set to done, and the file will not be merged again
joachim99@11:    if a directory merge is started.
joachim99@11: </para><para>
joachim99@11:    But note that this status information will be lost when you rerun a directory
joachim99@11:    scan: "Directory"-menu: "Rescan"
joachim99@11: </para>
joachim99@11: </sect2>
joachim99@11: </sect1>
joachim99@11: </chapter>
joachim99@11: 
joachim99@11: <chapter id="misc">
joachim99@11: <title>Miscellaneous Topics</title>
joachim99@11: <sect1 id="networktransparency">
joachim99@11: <title>Networktransparency via KIO</title>
joachim99@11: <sect2><title>KIO-Slaves</title>
joachim99@11: <para>
joachim99@11: KDE supports networktransparency via KIO-slaves. KDiff3 uses this
joachim99@11: for reading input files and for scanning directories.
joachim99@11: This means that you can specify files and directories on local and
joachim99@11: remote ressources via URLs.
joachim99@11: </para><para>
joachim99@11: Example:
joachim99@11: </para><para>
joachim99@11: <screen>
joachim99@11:    <command>kdiff3</command> test.cpp  ftp://ftp.faraway.org/test.cpp
joachim99@11:    <command>kdiff3</command> tar:/home/hacker/archive.tar.gz/dir ./dir
joachim99@11: </screen>
joachim99@11: </para>
joachim99@11: <para>The first line compares a local file with a file on an FTP-server. The second line
joachim99@11: compares a directory within an compressed archive with a local directory.
joachim99@11: </para><para>
joachim99@11: Other KIO-slaves that are interesting are:
joachim99@11: </para>
joachim99@11: <itemizedlist>
joachim99@11: <listitem><para>Files from the WWW (http:),</para></listitem>
joachim99@11: <listitem><para>Files from the FTP (ftp:),</para></listitem>
joachim99@11: <listitem><para>Encrypted file transfer (fish:, sftp:),</para></listitem>
joachim99@11: <listitem><para>Windows-ressources (smb:),</para></listitem>
joachim99@11: <listitem><para>Local files (file:),</para></listitem>
joachim99@11: </itemizedlist>
joachim99@11: <para>
joachim99@11: Other things that are possible, but probably less useful are:
joachim99@11: </para>
joachim99@11: <itemizedlist>
joachim99@11: <listitem><para>Man-pages (man:),</para></listitem>
joachim99@11: <listitem><para>Info-pages (info:),</para></listitem>
joachim99@11: </itemizedlist>
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: <sect2><title>How To Write URLs</title>
joachim99@11: <para>
joachim99@11:    An URL has a different syntax compared with paths for local files and directories.
joachim99@11:    Some things should be considered:
joachim99@11: </para>
joachim99@11: <itemizedlist>
joachim99@11: <listitem><para>
joachim99@11:    A path can be relative and can contain "." or "..". This is not possible for URLs which are always absolute.
joachim99@11: </para></listitem><listitem><para>
joachim99@11:    Special characters must be written with "escaping". ("#"->"%23", space->"%20", etc.)
joachim99@11:    E.g. A file with the name "/#foo#" would have the URL "file:/%23foo%23".
joachim99@11: </para></listitem><listitem><para>
joachim99@11:    When URLs don't work as expected, try to open them in Konqueror first.
joachim99@11: </para></listitem>
joachim99@11: </itemizedlist>
joachim99@11: 
joachim99@11: </sect2>
joachim99@11: 
joachim99@11: <sect2><title>Capabilities of KIO-Slaves</title>
joachim99@11: <para>
joachim99@11:    Networktransparency has one drawback: Not all ressources have the same cababilities.
joachim99@11: </para><para>
joachim99@11:    Sometimes this is due to the filesystem of the server, sometimes due to the protocol.
joachim99@11:    Here is a short list of restrictions:
joachim99@11: </para>
joachim99@11: <itemizedlist>
joachim99@11: <listitem><para>
joachim99@11:    Sometimes there is no support for links.
joachim99@11: </para></listitem><listitem><para>
joachim99@11:    Or there is no way to distinguish if a link points to a file or a directory; always assuming a file. (ftp:, sftp:).
joachim99@11: </para></listitem><listitem><para>
joachim99@11:    Can't always determine the filesize.
joachim99@11: </para></listitem><listitem><para>
joachim99@11:    Limited support for permissions.
joachim99@11: </para></listitem><listitem><para>
joachim99@11:    No possibility to modify permissions or modification time, so permissions or time of a copy will differ from the original.
joachim99@11:    (Only possible for local files.)
joachim99@11: </para></listitem>
joachim99@11: </itemizedlist>
joachim99@11: </sect2>
joachim99@11: </sect1>
joachim99@11: 
joachim99@11: <sect1 id="kpart">
joachim99@11: <title>Using &kdiff3; as a KPart</title>
joachim99@11: <para>
joachim99@11: &kdiff3; is a KPart. Currently it implements the KParts::ReadOnlyPart-interface.
joachim99@11: </para><para>
joachim99@11: It's main use is as difference-viewer in KDevelop. KDevelop always starts the
joachim99@11: internal difference viewer first. To invoke KDiff3 press the right mouse button
joachim99@11: on the difference viewer window and select "Show in KDiff3Part" from the contextmenu.
joachim99@11: </para><para>
joachim99@11: KDiff3 normally requires two complete files as input. When used as part KDiff3
joachim99@11: will assume that the inputfile is a patch-file in the unified format. KDiff3
joachim99@11: then retrieves the original filenames from the patch-file. At least one of
joachim99@11: the two files must be available. KDiff3 will then invoke <command>patch</command> to
joachim99@11: recreate the second file.
joachim99@11: </para><para>
joachim99@11: In Konqueror you can select a patch-file and select "Preview in"-"KDiff3Part" from
joachim99@11: the contextmenu. Be aware that this won't work if none of the original files are
joachim99@11: available, and it is not reliable if the original file(s) have changed since the
joachim99@11: patch-file was generated.
joachim99@11: </para><para>
joachim99@11: When run as a part KDiff3 only provides the a two-file-diff, a very small toolbar
joachim99@11: and menu. Merging or directory-comparison are not supported then.
joachim99@11: </para>
joachim99@11: </sect1>
joachim99@11: </chapter>
joachim99@11: 
joachim99@11: <chapter id="faq">
joachim99@11: <title>Questions and Answers</title>
joachim99@11: 
joachim99@11: &reporting.bugs;
joachim99@11: &updating.documentation;
joachim99@11: 
joachim99@11: <qandaset id="faqlist">
joachim99@11: 
joachim99@11: <qandaentry><question><para>
joachim99@11:    Why is it called "KDiff3"?
joachim99@11: </para></question><answer><para>
joachim99@11:    Tools named "KDiff" and "KDiff2" (now called "Kompare") already exist. Also "KDiff3" should suggest
joachim99@11:    that it can merge like the "diff3"-tool in the Diff-Tool collection.
joachim99@11: </para></answer></qandaentry>
joachim99@11: 
joachim99@11: <qandaentry><question><para>
joachim99@11:    Why did I release it under GPL?
joachim99@11: </para></question><answer><para>
joachim99@11:    I'm using GPL programs for a very long time now and learned very much
joachim99@11:    by  having a look at many of the sources. Hence this is my "Thank You"
joachim99@11:    to   all  programmers that also did so or will do the same.
joachim99@11: </para></answer></qandaentry>
joachim99@11: 
joachim99@11: <qandaentry><question><para>
joachim99@11:    Some buttons and functions are missing. What's wrong?
joachim99@11: </para></question><answer><para>
joachim99@11:    You compiled from source but you probably didn't specify the correct KDE-prefix
joachim99@11:    with configure. By default configure wants to install in /usr/local but then KDE can't
joachim99@11:    find the user-interface ressource file (i.e. kdiff3ui.rc). The README-file contains
joachim99@11:    more information about the correct prefix.
joachim99@11: </para></answer></qandaentry>
joachim99@11: 
joachim99@11: <qandaentry><question><para>
joachim99@11:    Often lines that are similar but not identical appear next to each other
joachim99@11:    but sometimes not. Why?
joachim99@11: </para></question><answer><para>
joachim99@11:    Lines where only the amount of white space characters is different
joachim99@11:    are   treated as "equal" at first, while just one different non-white character
joachim99@11:    causes the lines to be "different". If similar lines appear next to each
joachim99@11:    other, this actually is coincidence but this fortunately is often the case.
joachim99@11: </para></answer></qandaentry>
joachim99@11: 
joachim99@11: <qandaentry><question><para>
joachim99@11:    Why must all conflicts be solved before the merge result can be saved?
joachim99@11: </para></question><answer><para>
joachim99@11:    For each equal or different section the editor in the merge result
joachim99@11:    window    remembers where it begins or ends. This is needed so that conflicts
joachim99@11:    can  be solved manually by simply selecting the source button (A, B or C).
joachim99@11:    This  information is lost while saving as text and it is too much effort to
joachim99@11:    create  a special file format that supports saving and restoring all necessary
joachim99@11:    information.
joachim99@11: </para></answer></qandaentry>
joachim99@11: 
joachim99@11: <qandaentry><question><para>
joachim99@11:    Why does the editor in the merge result window not have an "undo"-function?
joachim99@11: </para></question><answer><para>
joachim99@11:   This was too much effort until now. You can always
joachim99@11:   restore a version from one source (A, B or C) by clicking the respective
joachim99@11:   button. For big editing the use of another editor is recommended anyway.
joachim99@11: </para></answer></qandaentry>
joachim99@11: 
joachim99@11: <qandaentry><question><para>
joachim99@11:    When I removed some text, then suddenly "&lt;No src line&gt;" appeared
joachim99@11:    and can't be deleted. What does that mean and how can one remove this?
joachim99@11: </para></question><answer><para>
joachim99@11:    For each equal or different section the editor in the merge result
joachim99@11:    window    remembers where it begins or ends. "&lt;No src line&gt;" means
joachim99@11:    that    there is nothing left in a section, not even a new line character.
joachim99@11:    This  can happen either while merging automatically or by editing. This is
joachim99@11:    no problem,   since this hint won't appear in the saved file. If you want
joachim99@11:    the orignal source  back just select the section (click on the left summary
joachim99@11:    column) and then click the source button with the needed contents (A/B or
joachim99@11:    C).
joachim99@11: </para></answer></qandaentry>
joachim99@11: 
joachim99@11: <qandaentry><question><para>
joachim99@11:    Why doesn't KDiff3 support syntax-highlighting?
joachim99@11: </para></question><answer><para>
joachim99@11:    KDiff3 already uses many colors for difference highlighting. More
joachim99@11:    highlighting    would be confusing. Use another editor for this.
joachim99@11: </para></answer></qandaentry>
joachim99@11: 
joachim99@11: <qandaentry><question><para>
joachim99@11:    There is so much information here, but your question is still not answered?
joachim99@11: </para></question><answer><para>
joachim99@11:    Please send me your question. I appreciate every comment.
joachim99@11: </para></answer></qandaentry>
joachim99@11: 
joachim99@11: </qandaset>
joachim99@11: </chapter>
joachim99@11: 
joachim99@11: <chapter id="credits">
joachim99@11: 
joachim99@11: <title>Credits and License</title>
joachim99@11: 
joachim99@11: <para>
joachim99@11: &kdiff3; - File and Directory Comparison and Merge Tool
joachim99@11: </para>
joachim99@11: <para>
joachim99@11: Program copyright 2002-2003 Joachim Eibl <email>joachim.eibl@gmx.de</email>
joachim99@11: </para>
joachim99@11: <para>
joachim99@11: Several cool ideas and bugreports came from colleagues and many people out in the Wild Wild Web. Thank you!
joachim99@11: </para>
joachim99@11: 
joachim99@11: <para>
joachim99@11: Documentation Copyright &copy; 2002-2003 Joachim Eibl <email>joachim.eibl@gmx.de</email>
joachim99@11: </para>
joachim99@11: 
joachim99@11: <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
joachim99@11: 
joachim99@11: &underFDL;               <!-- FDL: do not remove -->
joachim99@11: 
joachim99@11: 
joachim99@11: &underGPL;        	 <!-- GPL License -->
joachim99@11: 
joachim99@11: </chapter>
joachim99@11: 
joachim99@11: <appendix id="installation">
joachim99@11: <title>Installation</title>
joachim99@11: 
joachim99@11: <sect1 id="getting-kdiff3">
joachim99@11: <title>How to obtain &kdiff3;</title>
joachim99@11: 
joachim99@11: <para>
joachim99@11: You can download the latest version of KDiff3 from its homepage <ulink url="http://kdiff3.sourceforge.net">http://kdiff3.sourceforge.net</ulink>.
joachim99@11: </para><para>
joachim99@11: KDiff3 is also available for other platforms. See the homepage for details.
joachim99@11: </para>
joachim99@11: 
joachim99@11: 
joachim99@11: </sect1>
joachim99@11: 
joachim99@11: <sect1 id="requirements">
joachim99@11: <title>Requirements</title>
joachim99@11: 
joachim99@11: <para>
joachim99@11:    In order to successfully use all features of &kdiff3;, you need &kde; >3.1. The
joachim99@11:    diff-tool from the <ulink url="http://www.gnu.org/software/diffutils/diffutils.html">GNU-diff-utils</ulink>
joachim99@11:    is recommended for best results.
joachim99@11: </para><para>
joachim99@11:    For information about how to run KDiff3 on other platforms without KDE please see the
joachim99@11:    <ulink url="http://kdiff3.sourceforge.net">homepage</ulink>.
joachim99@11: </para><para>
joachim99@11: You can find a list of changes at <ulink
joachim99@11: url="http://kdiff3.sourceforge.net/ChangeLog">http://kdiff3.sourceforge.net/ChangeLog</ulink>
joachim99@11: or in the "ChangeLog"-file of the source package.
joachim99@11: </para>
joachim99@11: </sect1>
joachim99@11: 
joachim99@11: <sect1 id="compilation">
joachim99@11: <title>Compilation and Installation</title>
joachim99@11: 
joachim99@11: <para>In order to compile and install &kdiff3; on a system with KDE, type the
joachim99@11: following in the base directory of the &kdiff3; distribution:</para>
joachim99@11: 
joachim99@11: <screen><prompt>%</prompt> <userinput><command>./configure --prefix=<replaceable>kde-dir</replaceable></command></userinput>
joachim99@11: <prompt>%</prompt> <userinput><command>make</command></userinput>
joachim99@11: <prompt>%</prompt> <userinput><command>make</command> install</userinput>
joachim99@11: </screen>
joachim99@11: <para>
joachim99@11: <replaceable>kde-dir</replaceable> specifies the directory
joachim99@11: containing KDE on your system. If you are not sure, read the README-file for details.
joachim99@11: </para>
joachim99@11: <para>Since &kdiff3; uses <command>autoconf</command> and
joachim99@11: <command>automake</command> you should have no trouble compiling it. Should you
joachim99@11: run into problems please report them to the &kde; mailing lists.</para>
joachim99@11: 
joachim99@11: </sect1>
joachim99@11: 
joachim99@11: </appendix>
joachim99@11: 
joachim99@11: &documentation.index;
joachim99@11: </book>
joachim99@11: 
joachim99@11: <!--
joachim99@11: Local Variables:
joachim99@11: mode: sgml
joachim99@11: sgml-minimize-attributes:nil
joachim99@11: sgml-general-insert-case:lower
joachim99@11: sgml-indent-step:0
joachim99@11: sgml-indent-data:nil
joachim99@11: End:
joachim99@11: 
joachim99@11: vim:tabstop=2:shiftwidth=2:expandtab
joachim99@11: -->